fix(project): validate runtimeVersion on CodeZip runtimes - #1972

Rebased onto current refactor. Both parents (#1969, #1970) have merged, and refactor has since landed two of this PR's three parts independently — see "What the rebase changed" below.

The gap

The CDK construct library's AgentEnvSpecSchema refines:

if (data.build !== 'Container' && !data.runtimeVersion) {
  // "runtimeVersion is required for CodeZip builds"
}

Our copy of that schema marked the field plain .optional(), with no such rule. So the CLI accepted a spec that synthesis would refuse, and the user only discovered it after a full tsc + cdk synth — from a stack trace inside the generated app rather than from the CLI.

Our superRefine already mirrors the library's checks almost one for one, including the identical container-only-fields loop directly beneath. This adds the one that was missing, in the same position the library has it:

if (data.build !== "Container" && !data.runtimeVersion) {
  ctx.addIssue({
    code: "custom",
    message: "runtimeVersion is required for CodeZip builds",
    path: ["runtimeVersion"],
  });
}

Container builds take their version from the image and stay exempt, consistent with the check below it.

Reporting the rule earlier is only useful if it says what to fix

DeserializationError named the file and nothing else:

Failed to deserialize file at /path/to/agentcore/agentcore.json

The zod issues were attached as cause, which nothing renders — they were reachable only from the debug log. So the user traded CDK's precise runtimes[0].runtimeVersion: runtimeVersion is required for CodeZip builds for a message that doesn't name a field.

DeserializationError now takes an optional detail, and json.read() fills it with z.prettifyError():

Failed to deserialize file at "/path/to/agentcore/agentcore.json"
✖ runtimeVersion is required for CodeZip builds
  → at runtimes[0].runtimeVersion

Putting it in json.read() rather than in the project manager means every caller of json.read() benefits, not just agentcore.json. A JSON syntax error carries no zod issues, so that path is unchanged and still covered by its existing test.

Blast radius

ProjectSpecSchema has exactly one consumer: resolve() at manager.tsx:56. So the only configs this newly rejects are ones the CDK app would also reject at synth — no workflow that previously succeeded starts failing. It does mean the whole CLI now refuses to load such a config rather than failing at build time, which is the intent.

Two test fixtures were CodeZip runtimes without runtimeVersion and are now invalid by this rule, so they gain one (projectSchemas/runtime.test.ts, projectSchemas/project.test.ts). Worth a look during review that the surrounding assertions still test what they claim — the security-group-cap test at runtime.test.ts asserts a CodeZip spec succeeds, so it would have silently started passing for the wrong reason had the fixture not been fixed.

What the rebase changed

Two of the three original commits are now redundant, so the branch is a single commit:

• Promoting DeserializationError to a USER-sourced AgentCoreCLIError landed on refactor independently. Only the detail option is new here.
• Removing the try/catch wrapper in resolve() also landed on refactor independently. manager.tsx is no longer touched by this PR at all.
• The earlier review round replaced a hand-rolled describeValidationFailure with z.prettifyError and moved the detail into json.ts (thanks @Hweinstock). That is the shape above; the intermediate commit no longer stood on its own after the rebase, so the two were squashed.

Verification

Against the same real scaffolded project used to verify #1970, with runtimeVersion removed from its agentcore.json:

• Before: tsc ran, cdk synth ran, then the construct library's zod error.
• After: the CLI stops at config load naming runtimes[0].runtimeVersion — no compile, no synth, no node_modules needed.

New unit tests: the rule rejects a CodeZip runtime with no runtimeVersion and reports it at path: ["runtimeVersion"]; a container runtime without one still validates; and resolve() surfaces the reason in its message.

• bun test — 1600 pass, 2 fail. Both failures are Cannot find package 'aws-cdk-lib' loading the CDK template assets (src/assets/cdk/test/cdk.test.ts), which are meant to run inside a scaffolded project and are unrelated to this diff.
• tsc --noEmit clean, oxlint clean, prettier --check clean on all six touched files.